xds: Implementation of Unified Matcher by shivaspeaks · Pull Request #12640 · grpc/grpc-java

shivaspeaks · 2026-02-03T09:46:09Z

Implements gRFC A106: xDS Unified Matcher
grpc/proposal#520

l46kok

Sorry about the drive-by -- I happened to notice this while putting together an unrelated PR in CEL-Java. I'll hold off on submitting it on our end.

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

Also removes antlr dependency from `dev.cel:runtime` artifact Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

Also removes antlr dependency from `dev.cel:runtime` artifact Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 872010923

asheshvidyut

Reviewing for learning purposes.

…atcher

kannanjgithub

Reviewed source code, yet to review tests.

Copilot

Pull request overview

Implements gRFC A106 “xDS Unified Matcher” in the io.grpc.xds.internal.matcher package, adding a proto-driven matcher runtime (list/tree forms), pluggable input/matcher registries, and CEL-based matching support, along with extensive validation and behavior tests.

Changes:

Added UnifiedMatcher runtime with MatcherList/MatcherTree execution, OnMatch handling, recursion-depth validation, and MatchResult aggregation semantics.
Introduced pluggable registries (MatchInputRegistry, MatcherRegistry) and concrete implementations for header inputs and CEL-state matching.
Added comprehensive unit tests covering validation, keep-matching semantics, matcher-tree behaviors, and CEL matching/extraction.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
xds/src/test/java/io/grpc/xds/internal/matcher/UnifiedMatcherValidationTest.java	New validation tests for unified matcher parsing and input/matcher constraints.
xds/src/test/java/io/grpc/xds/internal/matcher/UnifiedMatcherTest.java	New behavioral tests for matcher list semantics, inputs, and runner behavior.
xds/src/test/java/io/grpc/xds/internal/matcher/MatcherTreeTest.java	New behavioral tests for matcher tree exact/prefix matching and keep-matching behavior.
xds/src/test/java/io/grpc/xds/internal/matcher/CelStateMatcherTest.java	New tests for CEL matcher integration, type mismatches, and safe failure modes.
xds/src/test/java/io/grpc/xds/internal/matcher/CelMatcherTestHelper.java	Test helper updates to compile CEL matchers/extractors for test cases.
xds/src/main/java/io/grpc/xds/internal/Matchers.java	Extended internal string matcher to support `contains` with `ignoreCase`.
xds/src/main/java/io/grpc/xds/internal/MatcherParser.java	Added parsing for `com.github.xds.type.matcher.v3.StringMatcher` and `ignoreCase` contains.
xds/src/main/java/io/grpc/xds/internal/matcher/UnifiedMatcher.java	New core unified matcher entry point and recursion-depth validation.
xds/src/main/java/io/grpc/xds/internal/matcher/PredicateEvaluator.java	New predicate evaluation implementation for single/or/and/not matchers.
xds/src/main/java/io/grpc/xds/internal/matcher/OnMatch.java	New “action vs nested matcher” handling and action type validation hook.
xds/src/main/java/io/grpc/xds/internal/matcher/MatchResult.java	New immutable match result carrying actions and terminal-match state.
xds/src/main/java/io/grpc/xds/internal/matcher/MatchInputRegistry.java	New registry for match input providers (header, CEL env).
xds/src/main/java/io/grpc/xds/internal/matcher/MatchInputProvider.java	New provider interface for building `MatchInput` from typed configs.
xds/src/main/java/io/grpc/xds/internal/matcher/MatchInput.java	New abstraction for extracting typed values from a `MatchContext`.
xds/src/main/java/io/grpc/xds/internal/matcher/MatcherTree.java	New matcher-tree implementation with exact map and prefix trie matching.
xds/src/main/java/io/grpc/xds/internal/matcher/MatcherRunner.java	New helper to run matchers and return terminal actions.
xds/src/main/java/io/grpc/xds/internal/matcher/MatcherRegistry.java	New registry for custom matcher providers (e.g., CEL).
xds/src/main/java/io/grpc/xds/internal/matcher/MatcherProvider.java	New provider interface for building `Matcher` implementations from typed configs.
xds/src/main/java/io/grpc/xds/internal/matcher/MatcherList.java	New matcher-list implementation with keep-matching and on-no-match behavior.
xds/src/main/java/io/grpc/xds/internal/matcher/Matcher.java	New matcher interface with optional declared input type.
xds/src/main/java/io/grpc/xds/internal/matcher/MatchContext.java	Extended match context to include request id and builder support.
xds/src/main/java/io/grpc/xds/internal/matcher/HttpAttributesCelMatchInput.java	New input that produces a CEL variable resolver from the match context.
xds/src/main/java/io/grpc/xds/internal/matcher/HeaderMatchInput.java	New header input implementation with binary/ASCII handling and validation.
xds/src/main/java/io/grpc/xds/internal/matcher/CelStateMatcher.java	New matcher provider for xDS CEL matcher extension with safe eval failure behavior.
xds/src/main/java/io/grpc/xds/internal/matcher/CelMatcher.java	New CEL matcher runtime wrapper for boolean expressions.

Comments suppressed due to low confidence (1)

xds/src/test/java/io/grpc/xds/internal/matcher/CelMatcherTestHelper.java:67

CelMatcherTestHelper.compile() / compileStringExtractor() call production compile methods that declare throws CelEvaluationException, but these helper methods don't declare or handle that checked exception. This will fail compilation if CelEvaluationException is checked (as it is in this codebase).

  public static CelMatcher compile(String expression)
      throws dev.cel.common.CelException {
    CelAbstractSyntaxTree ast = COMPILER.compile(expression).getAst();
    return CelMatcher.compile(ast);
  }

  public static CelStringExtractor compileStringExtractor(String expression)
      throws dev.cel.common.CelException {
    CelAbstractSyntaxTree ast = COMPILER.compile(expression).getAst();
    return CelStringExtractor.compile(ast);
  }

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Fine to merge with Kannan's review.

shivaspeaks force-pushed the xds-unified-matcher-and-cel branch from 082243d to f472c63 Compare February 3, 2026 10:11

shivaspeaks marked this pull request as ready for review February 8, 2026 09:01

shivaspeaks requested review from AgraVator, ejona86 and kannanjgithub February 8, 2026 09:02

l46kok reviewed Feb 11, 2026

View reviewed changes

Comment thread gradle/libs.versions.toml Outdated

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java Outdated

ejona86 reviewed Feb 12, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/CelMatcher.java Outdated

Comment thread gradle/libs.versions.toml Outdated

l46kok reviewed Feb 13, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java Outdated

copybara-service Bot pushed a commit to cel-expr/cel-java that referenced this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts

1c9d43e

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

copybara-service Bot mentioned this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts cel-expr/cel-java#954

Merged

copybara-service Bot pushed a commit to cel-expr/cel-java that referenced this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts

d960f42

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

copybara-service Bot pushed a commit to cel-expr/cel-java that referenced this pull request Feb 18, 2026

Properly establish cross dependenies across maven artifacts

6cac827

Fixes: #566 See also grpc/grpc-java#12640 PiperOrigin-RevId: 871541021

ejona86 requested a review from sergiitk February 23, 2026 18:02

ejona86 reviewed Feb 25, 2026

View reviewed changes

sergiitk previously requested changes Feb 25, 2026

View reviewed changes

ejona86 reviewed Feb 27, 2026

View reviewed changes

shivaspeaks mentioned this pull request Feb 25, 2026

xds: Add composite filter #12646

Open

shivaspeaks requested review from ejona86 and sergiitk March 4, 2026 10:53

asheshvidyut reviewed Mar 25, 2026

View reviewed changes

Restore MatchContext and CelMatcherTestHelper additions for Unified M…

f312c9c

…atcher

shivaspeaks force-pushed the xds-unified-matcher-and-cel branch from 8515729 to f312c9c Compare June 8, 2026 09:35

Remove cel.compiler dependency from interop-testing to fix CI

0af8751

shivaspeaks changed the title ~~xds: Implementation of Unified Matcher and CEL Integration~~ xds: Implementation of Unified Matcher Jun 11, 2026

AgraVator reviewed Jun 15, 2026

View reviewed changes

shivaspeaks added 2 commits June 19, 2026 11:24

Cache Metadata.Key and BaseEncoding in HeaderMatchInput

d86e0aa

review comments

89b2617

shivaspeaks requested review from AgraVator and kannanjgithub June 19, 2026 07:46

kannanjgithub requested changes Jun 26, 2026

View reviewed changes

Address comments

0bbc9e3

shivaspeaks requested a review from kannanjgithub June 26, 2026 11:07

kannanjgithub reviewed Jun 26, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/MatchResult.java Outdated

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/MatcherTree.java Outdated

rework addressing comments

81065a9

shivaspeaks requested a review from kannanjgithub June 29, 2026 07:41

kannanjgithub requested a review from Copilot June 30, 2026 07:41

Copilot started reviewing on behalf of kannanjgithub June 30, 2026 07:42 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

kannanjgithub requested changes Jun 30, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/MatchResult.java Outdated

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/MatcherList.java

resolve comments and add tests

addcfea

shivaspeaks requested a review from kannanjgithub July 1, 2026 07:24

kannanjgithub reviewed Jul 1, 2026

View reviewed changes

address nits

5e02211

shivaspeaks requested a review from kannanjgithub July 1, 2026 08:39

kannanjgithub reviewed Jul 1, 2026

View reviewed changes

Comment thread xds/src/main/java/io/grpc/xds/internal/matcher/UnifiedMatcher.java

add more uncovered branches in tests

a31d8d2

kannanjgithub approved these changes Jul 1, 2026

View reviewed changes

shivaspeaks merged commit 0cf5239 into grpc:master Jul 1, 2026
15 of 17 checks passed

shivaspeaks deleted the xds-unified-matcher-and-cel branch July 1, 2026 15:42

Uh oh!

Conversation

shivaspeaks commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

l46kok left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

asheshvidyut left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kannanjgithub left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

shivaspeaks commented Feb 3, 2026 •

edited

Loading